home *** CD-ROM | disk | FTP | other *** search
/ Aminet 21 / Aminet 21 (1997)(GTI - Schatztruhe)[!][Oct 1997].iso / Aminet / comm / misc / bZ_ZConnectLib.lha / ZConnectLib.lzh / ZConnectLib / Developer / Autodocs / zconnect.doc < prev   
Encoding:
Text File  |  1997-07-25  |  27.2 KB  |  857 lines
  1. TABLE OF CONTENTS
  2.  
  3. zconnect.library/--announce--
  4. zconnect.library/ZCon_AppendHeaderLine
  5. zconnect.library/ZCon_CheckHeader
  6. zconnect.library/ZCon_CheckRoute
  7. zconnect.library/ZCon_CreateDate
  8. zconnect.library/ZCon_CreateHeader
  9. zconnect.library/ZCon_CreateID
  10. zconnect.library/ZCon_FreeHeader
  11. zconnect.library/ZCon_GetDate
  12. zconnect.library/ZCon_GetHeader
  13. zconnect.library/ZCon_GetHeaderLineContents
  14. zconnect.library/ZCon_GetZConStr
  15. zconnect.library/ZCon_HeaderToIBM
  16. zconnect.library/ZCon_HeaderToISO
  17. zconnect.library/ZCon_NewCreateID
  18. zconnect.library/ZCon_RemHeaderLines
  19. zconnect.library/ZCon_RenameHeaderLines
  20. zconnect.library/ZCon_StringToIBM
  21. zconnect.library/ZCon_StringToISO
  22. zconnect.library/ZCon_WriteHeader
  23. zconnect.library/--announce--                   zconnect.library/--announce--
  24.  
  25.    TITLE
  26.        zconnect.library
  27.  
  28.    VERSION
  29.        4.0
  30.  
  31.    RELEASE DATE
  32.        25.07.1997
  33.  
  34.    DESCRIPTION
  35.        zconnect.library is a shared library for easy processing of headers
  36.        of so called ZConnect message buffers. It also offers several support
  37.        functions, such as functions for creating date strings or message
  38.        IDs.
  39.  
  40.        For those who don't know what ZConnect is: ZConnect is a format like
  41.        the one specified in RFC 822 ("Standard for the format of ARPA
  42.        internet text messages") - but simply another ;)
  43.  
  44.        Please note that the definitions of ZConnect are currently only
  45.        German, that's why the documentation of zconnect.library is German,
  46.        too.
  47.  
  48.    SPECIAL REQUIREMENTS
  49.        OS 2.04+
  50.  
  51.    AVAILABILITY
  52.        http://home.pages.de/~bZ
  53.        ftp://ftp.wustl.edu/pub/aminet/comm/misc/bZ_ZConnectLib.lha
  54.  
  55.    PRICE
  56.        Freeware
  57.        Please read the additional License.txt document for further details.
  58.  
  59.    AUTHOR
  60.        Maik "BLiZZeR" Schreiber <BLiZZeR@dame.de>
  61.        http://home.pages.de/~bZ
  62.  
  63.    DISTRIBUTION
  64.        Please read the additional License.txt document for further details.
  65. zconnect.library/ZCon_AppendHeaderLine zconnect.library/ZCon_AppendHeaderLine
  66.  
  67.    NAME
  68.        ZCon_AppendHeaderLine -- Fügt eine Headerzeile an.
  69.  
  70.    SYNOPSIS
  71.        line = ZCon_AppendHeaderLine(list, id, contents)
  72.        D0                           A0    A1  A2
  73.  
  74.        struct ZConnectHeaderLine *ZCon_AppendHeaderLine(struct List *,
  75.            STRPTR, STRPTR);
  76.  
  77.    FUNCTION
  78.        Diese Funktion hängt eine Headerzeile an einen ZConnect-Header an.
  79.  
  80.    INPUTS
  81.        list     - Zeiger auf die List-Struktur des Headers
  82.        id       - Kennung der anzuhängenden Headerzeile (z.B. "ABS")
  83.                   *ohne* ":"
  84.        contents - Inhalt der anzuhängenden Headerzeile oder NULL
  85.  
  86.    RESULT
  87.        line     - Zeiger auf die ZConnectHeaderLine-Struktur der ange-
  88.                   hängten Headerzeile oder NULL im Fehlerfall
  89.  
  90.    NOTES
  91.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  92.        werden mittels AllocVec() angelegt. Sollen sie programmtechnisch
  93.        verändert werden, ist der Speicherbereich einfach mittels FreeVec()
  94.        freizugeben und ein neuer mittels AllocVec() zu allokieren. Die
  95.        Adresse wird dann wieder in der Struktur abgelegt.
  96.  
  97.        Ein eventueller Doppelpunkt am Ende von id wird abgetrennt.
  98.  
  99.        Eventuelle führende Whitespaces am Anfang von contents werden
  100.        abgetrennt.
  101.  
  102.        Die Headerzeilen werden mittels Enqueue() an die Liste gehängt,
  103.        das Feld zhl_ListNode.ln_Pri der ZConnectHeaderLine-Struktur kann
  104.        also benutzt werden.
  105.  
  106.        Ab V2 kann für contents auch NULL übergeben werden, der Inhalt der
  107.        Headerzeile ist dann leer ("").
  108.  
  109.    BUGS
  110.        Frühere Versionen akzeptierten keinen Leerstring ("") für contents.
  111.        Dies wurde in V2 behoben. Workaround: " " oder "\t" für contents
  112.        übergeben.
  113.  
  114.    SEE ALSO
  115.        ZCon_RemHeaderLines(), exec.library/Enqueue()
  116. zconnect.library/ZCon_CheckHeader           zconnect.library/ZCon_CheckHeader
  117.  
  118.    NAME
  119.        ZCon_CheckHeader -- Checkt einen kompletten ZConnect-Header.
  120.  
  121.    SYNOPSIS
  122.        error = ZCon_CheckHeader(list)
  123.        D0                       A0
  124.  
  125.        ULONG ZCon_CheckHeader(struct List *);
  126.  
  127.    FUNCTION
  128.        Diese Funktion überprüft einen kompletten ZConnect-Header.
  129.        Dabei werden die folgenden Checks durchgeführt:
  130.  
  131.        - Alle Pflicht-Headerzeilen müssen auftreten.
  132.          Befindet sich eine Pflicht-Headerzeile nicht im Header, gibt die
  133.          Funktion ZCCHECK_NO_xxx zurück, wobei xxx der Kennung der im
  134.          Header fehlenden Headerzeile entspricht.
  135.  
  136.        - Alle Headerzeilen, die nur einmal auftreten dürfen, werden
  137.          überprüft.
  138.          Befindet sich eine Headerzeilen-Kennung mehrfach im Header, gibt
  139.          die Funktion ZCCHECK_TOO_MANY_xxx zurück, wobei xxx der Kennung
  140.          der im Header mehrfach auftretenden Headerzeile entspricht.
  141.  
  142.        - Die Inhalte der Headerzeilen EDA, DDA, LDA, O-EDA und SPERRFRIST
  143.          werden überprüft.
  144.          Entsprechen die Inhalte nicht der Definition in der ZConnect-Doku-
  145.          mentation, gibt die Funktion je nach Kennung ZCCHECK_WRONG_EDA,
  146.          ZCCHECK_WRONG_DDA, ZCCHECK_WRONG_LDA, ZCCHECK_WRONG_O_EDA bzw.
  147.          ZCCHECK_WRONG_SPERRFRIST zurück.
  148.  
  149.        - Die Inhalte der Headerzeilen LEN und KOM werden geprüft, wobei
  150.          KOM eine Zahl enthalten muß, die kleiner oder gleich der Zahl
  151.          in LEN ist. Für beide ist der Wert 0 erlaubt.
  152.          Enthält die Headerzeile LEN keine reine Zahl oder ist diese
  153.          Zahl kleiner als die Zahl in der Headerzeile KOM, gibt die
  154.          Funktion ZCCHECK_WRONG_LEN zurück. Enthält die Headerzeile KOM
  155.          keine reine Zahl, gibt die Funktion ZCCHECK_WRONG_KOM zurück.
  156.  
  157.        - Der Inhalt der Headerzeile PRIO wird überprüft.
  158.          Enthält diese nicht "0", "10" oder "20", gibt die Funktion
  159.          ZCCHECK_WRONG_PRIO zurück.
  160.  
  161.    INPUTS
  162.        list  - Zeiger auf die List-Struktur des zu überprüfenden ZConnect-
  163.                Headers
  164.  
  165.    RESULT
  166.        error - ZCCHECK_OK, wenn der Header in Ordnung ist, sonst eine der
  167.                Fehlermeldungen ZCCHECK_xxx
  168.  
  169.    NOTES
  170.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  171.  
  172.        Unbekannte Headerzeilen-Kennungen, die nicht mit dem in der
  173.        ZConnect-Dokumentation definierten Präfix "X-" beginnen, werden
  174.        nicht als unbekannt erkannt, da die Weiterentwicklung von ZConnect
  175.        derzeit nicht geklärt ist. Für weitere Fragen ist die Newsgroup
  176.        de.comm.protocols.zconnect von Interesse.
  177.  
  178.        Folgende Headerzeilen werden erst ab V2 überprüft:
  179.  
  180.          CONTROL: ADD      -----.
  181.          CONTROL: CANCEL        |
  182.          CONTROL: DEL           |
  183.          STAT: AUTO             |
  184.          STAT: CTL              |-- dürfen jeweils nur einmal auftreten
  185.          STAT: EB               |
  186.          STAT: NOCIPHER         |
  187.          STAT: NOKOP            |
  188.          STAT: TRACE       -----'
  189.  
  190.        Eventuell werden in Zukunft noch weitere Fehlermeldungen implemen-
  191.        tiert.
  192.  
  193.    SEE ALSO
  194.        <libraries/zconnect.h>,
  195.        ZConnect-Dokumentation (Kapitel "Datumsangaben")
  196. zconnect.library/ZCon_CheckRoute             zconnect.library/ZCon_CheckRoute
  197.  
  198.    NAME
  199.        ZCon_CheckRoute -- Findet ein System in einem Routepfad. (V3)
  200.  
  201.    SYNOPSIS
  202.        count = ZCon_CheckRoute(route, system)
  203.        D0                      A1     A2
  204.  
  205.        ULONG ZCon_CheckRoute(STRPTR, STRPTR);
  206.  
  207.    FUNCTION
  208.        Diese Funktion stellt fest, wie oft ein bestimmter Systemname (inkl.
  209.        Domain) in einem Routepfad auftritt.
  210.  
  211.    INPUTS
  212.        route  - der zu durchsuchende Routepfad
  213.        system - das zu suchende System (evtl. inkl. Domain)
  214.  
  215.    RESULT
  216.        count  - Anzahl der Auftreten des zu suchenden Systemnamen
  217.  
  218.    EXAMPLE
  219.        /* dies liefert "1" */
  220.        printf("%lu\n", ZCon_CheckRoute("a!b!c", "b"));
  221.  
  222.        /* dies liefert auch "1" */
  223.        printf("%lu\n", ZCon_CheckRoute("a!b!c", "B"));
  224.  
  225.        /* dies liefert ebenfalls "1" */
  226.        printf("%lu\n", ZCon_CheckRoute("a!bc!B!cb!b.do.main!c", "b"));
  227.  
  228.    NOTES
  229.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  230.  
  231.        Systeme werden nur gefunden, wenn sie wie im Routepfad angegeben
  232.        werden. Zum Beispiel wird das System "ABC" niemals gefunden, wenn es
  233.        im Routepfad nur als "ABC.de" auftritt.
  234.  
  235.    SEE ALSO
  236.        ZConnect-Dokumentation (Kapitel "Rekursionscheck anhand des Route-
  237.        pfads (ROT)")
  238. zconnect.library/ZCon_CreateDate             zconnect.library/ZCon_CreateDate
  239.  
  240.    NAME
  241.        ZCon_CreateDate -- Erzeugt ZConnect-Datumsangabe. (V2)
  242.  
  243.    SYNOPSIS
  244.        ZCon_CreateDate(date, offset, summertime, buffer)
  245.                        A1    D0      D1          A2
  246.  
  247.        void ZCon_CreateDate(struct ClockData *, WORD, UBYTE, STRPTR);
  248.  
  249.    FUNCTION
  250.        Diese Funktion erzeugt eine Datumsangabe im ZConnect-Format. Dabei
  251.        wird das Offset zur GMT addiert.
  252.  
  253.    INPUTS
  254.        date       - Zeiger auf eine ClockData-Struktur, die die aktuelle
  255.                     Systemzeit enthält
  256.        offset     - zu addierendes Offset zur GMT in Minuten
  257.        summertime - ZC_SUMMERTIME, wenn ein "S" für Sommerzeit eingefügt
  258.                     werden soll; ZC_WINTERTIME, wenn ein "W" für Winterzeit
  259.                     eingefügt werden soll; ZC_IGNORE, wenn keine Sommer-/
  260.                     Winterzeit-Angabe eingefügt werden soll
  261.        buffer     - Zeiger auf einen Puffer, in den die Datumsangabe
  262.                     geschrieben werden soll (muß mind. 22 Bytes groß sein!)
  263.  
  264.    EXAMPLE
  265.        UBYTE             buffer[22];
  266.        struct DateStamp  ds;
  267.        struct ClockData  cd;
  268.        struct Locale    *loc;
  269.        WORD              offs = 0;
  270.  
  271.        DateStamp(&ds);
  272.        Amiga2Date((ULONG) ds.ds_Days * 86400 +
  273.                   (ULONG) ds.ds_Minute * 60 +
  274.                   (ULONG) ds.ds_Tick / TICKS_PER_SECOND,
  275.                   &cd);
  276.  
  277.        if (loc = OpenLocale(NULL))
  278.        {
  279.          offs = (WORD) loc->loc_GMTOffset;
  280.          CloseLocale(NULL);
  281.        }
  282.  
  283.        ZCon_CreateDate(&cd, offs, ZC_IGNORE, buffer);
  284.        ZCon_AppendHeaderLine(header, "EDA", buffer);
  285.  
  286.    NOTES
  287.        Das zu übergebende Offset muß immer genau dem negativen Wert aus der
  288.        ZConnect-Dokumentation entsprechen, da es addiert wird! Ist also die
  289.        MET mit +1:00 gegeben, muß -60 (-1:00) übergeben werden!
  290.  
  291.        Das korrekte Offset kann bspw. ohne Änderungen direkt aus einer
  292.        Locale-Struktur übernommen werden (s.o.).
  293.  
  294.    SEE ALSO
  295.        ZCon_GetDate()
  296. zconnect.library/ZCon_CreateHeader         zconnect.library/ZCon_CreateHeader
  297.  
  298.    NAME
  299.        ZCon_CreateHeader -- Erzeugt einen neuen ZConnect-Header. (V3)
  300.  
  301.    SYNOPSIS
  302.        header = ZCon_CreateHeader()
  303.        D0
  304.  
  305.        struct List *ZCon_CreateHeader(void);
  306.  
  307.    FUNCTION
  308.        Diese Funktion erzeugt einen neuen (leeren) ZConnect-Header, der
  309.        mittels ZCon_FreeHeader() wieder freigegeben werden muß.
  310.  
  311.        Diese Funktion hätte eigentlich schon seit V1 existieren müssen...
  312.  
  313.    RESULT
  314.        header - Zeiger auf die List-Struktur des erzeugten ZConnect-Headers
  315.                 oder NULL im Fehlerfall
  316.  
  317.    EXAMPLE
  318.        struct List *header;
  319.  
  320.        if (header = ZCon_CreateHeader())
  321.        {
  322.          ZCon_AppendHeaderLine(header, "ABS", "BLiZZeR@dame.de");
  323.          ZCon_AppendHeaderLine(header, "EMP", "user@host.do.main");
  324.  
  325.          ZCon_WriteHeader(handle, header);
  326.  
  327.          ZCon_FreeHeader(header);
  328.        }
  329.  
  330.    SEE ALSO
  331.        ZCon_FreeHeader()
  332. zconnect.library/ZCon_CreateID                 zconnect.library/ZCon_CreateID
  333.  
  334.    NAME
  335.        ZCon_CreateID -- Erzeugt einzigartige ID. (V2) (OBSOLETE)
  336.  
  337.    SYNOPSIS
  338.        id = ZCon_CreateID(string)
  339.        D0                 A1
  340.  
  341.        ULONG ZCon_CreateID(STRPTR);
  342.  
  343.    FUNCTION
  344.        Diese Funktion erzeugt eine einzigartige ID, die z.B. als Message-ID
  345.        für ZConnect-Nachrichten verwandt werden kann.
  346.  
  347.    INPUTS
  348.        string - Ein beliebiger String, der zur Erzeugung der ID herangezogen
  349.                 wird. Hier kann z.B. die Adresse des Absenders übergeben
  350.                 werden.
  351.  
  352.    RESULT
  353.        id     - die erzeugte ID
  354.  
  355.    EXAMPLE
  356.        UBYTE  buffer[256];
  357.        STRPTR abs,
  358.               emp;
  359.  
  360.        abs = "BLiZZeR@dame.de";
  361.        emp = "user@host.do.main";
  362.  
  363.        ZCon_AppendHeaderLine(header, "ABS", abs);
  364.        ZCon_AppendHeaderLine(header, "EMP", emp);
  365.  
  366.        /* erzeugen einer weltweit einmaligen Message-ID */
  367.        sprintf(buffer, "%lx%lx%s",
  368.                ZCon_CreateID(abs),
  369.                ZCon_CreateID(emp),
  370.                strchr(abs, '@'));
  371.        ZCon_AppendHeaderLine(header, "MID", buffer);
  372.  
  373.    NOTES
  374.        Die ID wird mittels einer Hashfunktion erzeugt, die von der aktuellen
  375.        Systemzeit, dem übergebenen String sowie dem Rückgabewert der Funk-
  376.        tion GetUniqueID() der utility.library abhängig ist.
  377.  
  378.        Die Wahrscheinlichkeit, daß jemals die gleiche ID erzeugt wird, ist
  379.        daher nahezu 0.
  380.  
  381.        Bitte benutzen Sie ZCon_NewCreateID() statt dieser Funktion, da sie
  382.        einen besseren Algorithmus verwendet.
  383.  
  384.    SEE ALSO
  385.        ZCon_NewCreateID()
  386. zconnect.library/ZCon_FreeHeader             zconnect.library/ZCon_FreeHeader
  387.  
  388.    NAME
  389.        ZCon_FreeHeader -- Gibt kompletten ZConnect-Header frei.
  390.  
  391.    SYNOPSIS
  392.        ZCon_FreeHeader(list)
  393.                        A0
  394.  
  395.        void ZCon_FreeHeader(struct List *);
  396.  
  397.    FUNCTION
  398.        Diese Funktion gibt einen kompletten ZConnect-Header frei, der mit
  399.        ZCon_CreateHeader() oder ZCon_GetHeader() angelegt wurde.
  400.  
  401.    INPUTS
  402.        list - Zeiger auf die List-Struktur des freizugebenden ZConnect-
  403.               Headers oder NULL
  404.  
  405.    EXAMPLE
  406.        list = ZCon_GetHeader(handle);
  407.  
  408.        /* ... */
  409.  
  410.        ZCon_FreeHeader(list);
  411. zconnect.library/ZCon_GetDate                   zconnect.library/ZCon_GetDate
  412.  
  413.    NAME
  414.        ZCon_GetDate -- Liest Datum aus ZConnect-Datumsangabe aus. (V2)
  415.  
  416.    SYNOPSIS
  417.        offset = ZCon_GetDate(buffer, date, summertime)
  418.        D0                    A1      A2    A3
  419.  
  420.        WORD ZCon_GetDate(STRPTR, struct ClockData *, UBYTE *);
  421.  
  422.    FUNCTION
  423.        Diese Funktion liest ein Datum aus einer ZConnect-Datumsangabe.
  424.  
  425.    INPUTS
  426.        buffer     - Zeiger auf einen Puffer, der eine gültige ZConnect-
  427.                     Datumsangabe enthält
  428.        date       - Zeiger auf eine ClockData-Struktur, die das ausgelesene
  429.                     Datum aufnehmen soll (es werden *alle* Elemente der
  430.                     Struktur korrekt gesetzt)
  431.        summertime - Zeiger auf ein UBYTE, das die Sommer-/Winterzeit-Angabe
  432.                     aufnehmen soll (ZC_WINTERTIME, wenn ein "W" für Winter-
  433.                     zeit angegeben war; ZC_SUMMERTIME, wenn ein "S" für
  434.                     Sommerzeit angegeben war; ZC_IGNORE, wenn keines der
  435.                     beiden angegeben war)
  436.  
  437.  
  438.    RESULT
  439.        offset     - das in der Datumsangabe angegebene Offset in Minuten
  440.  
  441.    EXAMPLE
  442.        WORD             offset;
  443.        struct ClockData cd;
  444.        UBYTE            summertime;
  445.  
  446.        offset = ZCon_GetDate("19970608212044S+2", &cd, &summertime);
  447.  
  448.        printf("%02u.%02u.%u %02u:%02u:%02u, ",
  449.               cd.mday, cd.month, cd.year, cd.hour, cd.min, cd.sec);
  450.        if (summertime != ZC_IGNORE)
  451.          printf("%szeit, ",
  452.                 (summertime == ZC_WINTERTIME) ? "Winter" : "Sommer");
  453.        printf("Offset: %d min\n", offset);
  454.  
  455.    SEE ALSO
  456.        ZCon_CreateDate()
  457. zconnect.library/ZCon_GetHeader               zconnect.library/ZCon_GetHeader
  458.  
  459.    NAME
  460.        ZCon_GetHeader -- Liest ZConnect-Header aus Datei.
  461.  
  462.    SYNOPSIS
  463.        list = ZCon_GetHeader(filehandle)
  464.        D0                    A1
  465.  
  466.        struct List *ZCon_GetHeader(BPTR);
  467.  
  468.    FUNCTION
  469.        Diese Funktion liest einen kompletten ZConnect-Header aus einer
  470.        Datei in eine List-Struktur. Die Nodes der List-Struktur entsprechen
  471.        nach dem Einlesen der Struktur ZConnectHeaderLine.
  472.  
  473.    INPUTS
  474.        filehandle - Zeiger auf das FileHandle der zu lesenden Datei
  475.  
  476.    RESULT
  477.        list       - Zeiger auf die List-Struktur, die mittels
  478.                     ZCon_FreeHeader() wieder freigegeben werden muß,
  479.                     oder NULL im Fehlerfall
  480.  
  481.    EXAMPLE
  482.        BPTR         handle;
  483.        struct List *list;
  484.  
  485.        handle = Open(filename, MODE_OLDFILE);
  486.        list = ZCon_GetHeader(handle);
  487.  
  488.        if (list)
  489.        {
  490.          /* Ausgeben aller Headerzeilen */
  491.          if (!IsListEmpty(list))
  492.          {
  493.            struct ZConnectHeaderLine *l =
  494.                (struct ZConnectHeaderLine *) list->lh_Head;
  495.  
  496.            do
  497.            {
  498.              printf("%s: %s\n", l->zhl_ID, l->zhl_Contents);
  499.              l = (struct ZConnectHeaderLine *) l->zhl_ListNode.ln_Succ;
  500.            }
  501.            while ((APTR) l != (APTR) &list->lh_Tail);
  502.          }
  503.        }
  504.  
  505.    NOTES
  506.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  507.        werden mittels AllocVec() angelegt. Sollen sie programmtechnisch
  508.        verändert werden, ist der Speicherbereich einfach mittels FreeVec()
  509.        freizugeben und ein neuer mittels AllocVec() zu allokieren. Die
  510.        Adresse wird dann wieder in der Struktur abgelegt.
  511.  
  512.        Das Einlesen der Headerzeilen geschieht mit FGets(). Es ist daher
  513.        darauf zu achten, nur gepufferte Ein-/Ausgabe (FRead()) zu benutzen.
  514.  
  515.        Das Element zhl_ID der ZConnectHeaderLine-Struktur enthält nur die
  516.        reine Headerzeilen-Kennung, also ohne den Doppelpunkt.
  517.  
  518.        Eventuell führende Whitespaces werden vom Element zhl_Contents der
  519.        ZConnectHeaderLine-Struktur abgetrennt.
  520.  
  521.        Die Elemente zhl_ID und zhl_Contents der ZConnectHeaderLine-Struktur
  522.        werden (bis auf die o.g. Änderungen) unverändert eingelesen.
  523.  
  524.        Der eingelesene Header wird nicht gecheckt.
  525.  
  526.    SEE ALSO
  527.        ZCon_HeaderToISO(), ZCon_CheckHeader(), dos.library/FRead(),
  528.        IsListEmpty()
  529. zconnect.library/ZCon_GetHeaderLineContentslibrary/ZCon_GetHeaderLineContents
  530.  
  531.    NAME
  532.        ZCon_GetHeaderLineContents -- Holt Inhalt einer Headerzeile.
  533.  
  534.    SYNOPSIS
  535.        contents = ZCon_GetHeaderLineContents(list, id, storage)
  536.  
  537.        STRPTR ZCon_GetHeaderLineContents(struct List *, STRPTR,
  538.            struct ZConnectHeaderLine **);
  539.  
  540.    FUNCTION
  541.        Diese Funktion holt den Inhalt einer Headerzeile aus einem ZConnect-
  542.        Header.
  543.  
  544.    INPUTS
  545.        list     - Zeiger auf die List-Struktur des zu untersuchenden
  546.                   ZConnect-Headers
  547.        id       - Kennung der zu suchenden Headerzeile *ohne* ":"
  548.        storage  - Zeiger auf einen Zeiger auf eine ZConnectHeaderLine-
  549.                   Struktur, der einen Zeiger auf eine ZConnectHeaderLine-
  550.                   Struktur zu weiteren Abarbeitung des Header aufnimmt
  551.                   (muß vor dem ersten Aufruf mit NULL initialisiert
  552.                   werden). Ist keine weitere Abarbeitung gewünscht, ist
  553.                   NULL zu übergeben.
  554.  
  555.    RESULT
  556.        contents - Zeiger auf das Element zhl_Contents der ZConnectHeader-
  557.                   Line-Struktur, in der die Kennung auftrat
  558.  
  559.    EXAMPLE
  560.        /* Ausgeben des Inhalts der ABS:-Headerzeile */
  561.        STRPTR c;
  562.  
  563.        c = ZCon_GetHeaderLineContents(list, "ABS", NULL);
  564.        if (c)
  565.          printf("Absender: %s\n", l);
  566.  
  567.  
  568.        /* Ausgeben aller EMP:-Headerzeilen */
  569.        STRPTR c;
  570.        struct ZConnectHeaderLine *store = NULL;
  571.  
  572.        while (c = ZCon_GetHeaderLineContents(list, "EMP", &store))
  573.          printf("Empfänger: %s\n", c);
  574.  
  575.    NOTES
  576.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  577. zconnect.library/ZCon_GetZConStr             zconnect.library/ZCon_GetZConStr
  578.  
  579.    NAME
  580.        ZCon_GetZConStr -- Holt String aus Locale-Catalog. (V3)
  581.  
  582.    SYNOPSIS
  583.        string = ZCon_GetZConStr(id)
  584.        D0                       D0
  585.  
  586.        STRPTR ZCon_GetZConStr(ULONG);
  587.  
  588.    FUNCTION
  589.        Diese Funktion holt einen String aus dem Locale-Catalog der
  590.        zconnect.library, der beim ersten Öffnen der Library automatisch
  591.        geladen wird.
  592.  
  593.    INPUTS
  594.        id     - die Nummer des gewünschten Strings im Catalog; die Rückgabe-
  595.                 werte von ZCon_CheckHeader() können hierbei direkt benutzt
  596.                 werden
  597.  
  598.    RESULT
  599.        string - Zeiger auf den String im Catalog (read-only!) oder NULL im
  600.                 Fehlerfall (kein Catalog vorhanden, locale.library konnte
  601.                 nicht geöffnet werden, gewünschter String nicht vorhanden
  602.                 usw.)
  603.  
  604.    EXAMPLE
  605.        ULONG error;
  606.  
  607.        if (error = ZCon_CheckHeader(header))
  608.        {
  609.          STRPTR text;
  610.  
  611.          if (text = ZCon_GetZConStr(error))
  612.            printf("%s.\n", text);
  613.          else
  614.            puts("Kein Fehlertext verfügbar.");
  615.        }
  616.        else
  617.          puts("Keine Fehler.");
  618.  
  619.    SEE ALSO
  620.        MailDemon.cd
  621. zconnect.library/ZCon_HeaderToIBM           zconnect.library/ZCon_HeaderToIBM
  622.  
  623.    NAME
  624.        ZCon_HeaderToIBM -- Wandelt Header in IBM-Umlaute.
  625.  
  626.    SYNOPSIS
  627.        ZCon_HeaderToIBM(list)
  628.                         A0
  629.  
  630.        void ZCon_HeaderToIBM(struct List *);
  631.  
  632.    FUNCTION
  633.        Diese Funktion wandelt alle ISO-8859-1-Umlaute eines ZConnect-
  634.        Headers in IBM-Umlaute um.
  635.  
  636.    INPUTS
  637.        list - Zeiger auf die List-Struktur des umzuwandelnden ZConnect-
  638.        Headers
  639.  
  640.    SEE ALSO
  641.        ZCon_HeaderToISO(), ZCon_StringToIBM()
  642. zconnect.library/ZCon_HeaderToISO           zconnect.library/ZCon_HeaderToISO
  643.  
  644.    NAME
  645.        ZCon_HeaderToISO -- Wandelt Header in ISO-8859-1-Umlaute.
  646.  
  647.    SYNOPSIS
  648.        ZCon_HeaderToISO(list)
  649.                         A0
  650.  
  651.        void ZCon_HeaderToISO(struct List *);
  652.  
  653.    FUNCTION
  654.        Diese Funktion wandelt alle IBM-Umlaute eines ZConnect-Headers in
  655.        ISO-8859-1-Umlaute um.
  656.  
  657.    INPUTS
  658.        list - Zeiger auf die List-Struktur des umzuwandelnden ZConnect-
  659.               Headers
  660.  
  661.    SEE ALSO
  662.        ZCon_HeaderToIBM(), ZCon_StringToISO()
  663. zconnect.library/ZCon_NewCreateID           zconnect.library/ZCon_NewCreateID
  664.  
  665.    NAME
  666.        ZCon_NewCreateID -- Erzeugt einzigartige ID. (V3)
  667.  
  668.    SYNOPSIS
  669.        success = ZCon_NewCreateID(string, buffer)
  670.        D0                         A1      A2
  671.  
  672.        BOOL ZCon_NewCreateID(STRPTR, STRPTR);
  673.  
  674.    IMPORTANT NOTE
  675.        Ab V4 muß der Puffer mindestens 33 Byte groß sein (s. BUGS)!
  676.  
  677.    FUNCTION
  678.        Diese Funktion erzeugt eine einzigartige ID, die z.B. als Message-ID
  679.        für ZConnect-Nachrichten verwandt werden kann.
  680.  
  681.    INPUTS
  682.        string  - Ein beliebiger String, der zur Erzeugung der ID herange-
  683.                  zogen wird. Hier kann z.B. die Adresse des Absenders über-
  684.                  geben werden.
  685.        buffer  - Zeiger auf einen Puffer, der die erzeugte ID aufnehmen soll
  686.                  (muß mind. 33 Byte groß sein!). Die ID wird mit einem 0-
  687.                  Byte abgeschlossen.
  688.  
  689.    RESULT
  690.        success - TRUE, wenn die ID erfolgreich erzeugt werden konnte, sonst
  691.                  FALSE (kein temporärer Speicher verfügbar)
  692.  
  693.    EXAMPLE
  694.        UBYTE  id[33];
  695.        STRPTR abs;
  696.  
  697.        abs = "BLiZZeR@dame.de";
  698.        ZCon_AppendHeaderLine("ABS", abs);
  699.  
  700.        if (ZCon_NewCreateID(abs, id))
  701.          ZCon_AppendHeaderLine("MID", id);
  702.  
  703.    NOTES
  704.        Die ID wird mittels des RSA Data Security, Inc., MD5 Message-Digest
  705.        Algorithm erzeugt, dessen Ergebnis von der aktuellen Systemzeit, dem
  706.        übergebenen String sowie dem Rückgabewert der Funktion GetUniqueID()
  707.        der utility.library abhängig ist.
  708.  
  709.        Die Wahrscheinlichkeit, daß jemals die gleiche ID erzeugt wird, ist
  710.        daher nahezu 0.
  711.  
  712.    BUGS
  713.        V3 erzeugte einen defekten Pufferinhalt. Dies ist in V4 behoben.
  714.        Workaround: Explizit V4 öffnen.
  715.  
  716.    SEE ALSO
  717.        ZCon_CreateID()
  718. zconnect.library/ZCon_RemHeaderLines     zconnect.library/ZCon_RemHeaderLines
  719.  
  720.    NAME
  721.        ZCon_RemHeaderLines -- Entfernt Headerzeilen aus einem Header. (V2)
  722.  
  723.    SYNOPSIS
  724.        ZCon_RemHeaderLines(list, id, all)
  725.                            A0    A1  D0
  726.  
  727.        void ZCon_RemHeaderLines(struct List *, STRPTR, BOOL);
  728.  
  729.    FUNCTION
  730.        Diese Funktion entfernt alle Headerzeilen eines ZConnect-Headers,
  731.        deren Kennung gleich der übergebenen Kennung ist.
  732.  
  733.    INPUTS
  734.        list - Zeiger auf die List-Struktur des zu bearbeitenden ZConnect-
  735.               Headers
  736.        id   - Kennung der Headerzeilen *ohne* ":", die entfernt werden
  737.               sollen (z.B. "O-ROT")
  738.        all  - TRUE, wenn alle Headerzeilen mit der richtigen Kennung ent-
  739.               fernt werden sollen, sonst FALSE (hier wird nach Entfernen der
  740.               ersten richtigen Headerzeile abgebrochen)
  741.  
  742.    EXAMPLE
  743.        /* alle Headerzeilen, deren Kennung "EB" ist, entfernen */
  744.        ZCon_RemHeaderLines(header, "EB", TRUE);
  745.  
  746.    NOTES
  747.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  748.  
  749.    SEE ALSO
  750.        ZCon_AppendHeaderLine()
  751. zconnect.library/ZCon_RenameHeaderLinesconnect.library/ZCon_RenameHeaderLines
  752.  
  753.    NAME
  754.        ZCon_RenameHeaderLines -- Benennt Headerzeilenkennungen um. (V2)
  755.  
  756.    SYNOPSIS
  757.        ZCon_RenameHeaderLines(list, id, newid, all)
  758.                               A0    A1  A2     D0
  759.  
  760.        void ZCon_RenameHeaderLines(struct List *, STRPTR, STRPTR, BOOL);
  761.  
  762.    FUNCTION
  763.        Diese Funktion benennt alle Headerzeilenkennungen eines ZConnect-
  764.        Headers in eine andere Kennung um.
  765.  
  766.    INPUTS
  767.        list  - Zeiger auf die List-Struktur des zu bearbeitenden ZConnect-
  768.                Headers
  769.        id    - Kennung der zu suchenden Headerzeilen *ohne* ":" (z.B. "ROT")
  770.        newid - neue Kennung *ohne* ":" (z.B. "O-ROT")
  771.        all   - TRUE, wenn alle Headerzeilen mit der richtigen Kennung umbe-
  772.                nannt werden sollen, sonst FALSE (hier wird nach Umbenennen
  773.                der ersten richtigen Headerzeile abgebrochen)
  774.  
  775.    EXAMPLE
  776.        ZCon_RenameHeaderLines(header, "EMP", "OEM", FALSE);
  777.  
  778.    NOTES
  779.        Es wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  780. zconnect.library/ZCon_StringToIBM           zconnect.library/ZCon_StringToIBM
  781.  
  782.    NAME
  783.        ZCon_StringToIBM -- Wandelt String in IBM-Umlaute.
  784.  
  785.    SYNOPSIS
  786.        ZCon_StringToIBM(string)
  787.                         A1
  788.  
  789.        void ZCon_StringToIBM(STRPTR);
  790.  
  791.    FUNCTION
  792.        Diese Funktion wandelt alle ISO-8859-1-Umlaute eines String IBM-
  793.        Umlaute um.
  794.  
  795.    INPUTS
  796.        string - Zeiger auf den umzuwandelnden String
  797.  
  798.    SEE ALSO
  799.        ZCon_StringToISO(), ZCon_HeaderToIBM()
  800. zconnect.library/ZCon_StringToISO           zconnect.library/ZCon_StringToISO
  801.  
  802.    NAME
  803.        ZCon_StringToISO -- Wandelt String in ISO-8859-1-Umlaute.
  804.  
  805.    SYNOPSIS
  806.        ZCon_StringToISO(string)
  807.                         A1
  808.  
  809.        void ZCon_StringToISO(STRPTR);
  810.  
  811.    FUNCTION
  812.        Diese Funktion wandelt alle IBM-Umlaute eines Strings in ISO-8859-1-
  813.        Umlaute um.
  814.  
  815.    INPUTS
  816.        string - Zeiger auf den umzuwandelnden String
  817.  
  818.    SEE ALSO
  819.        ZCon_StringToIBM(), ZCon_HeaderToISO()
  820. zconnect.library/ZCon_WriteHeader           zconnect.library/ZCon_WriteHeader
  821.  
  822.    NAME
  823.        ZCon_WriteHeader -- Schreibt ZConnect-Header in Datei.
  824.  
  825.    SYNOPSIS
  826.        ZCon_WriteHeader(list, filehandle)
  827.                         A0    A1
  828.  
  829.        void ZCon_WriteHeader(struct List *, BPTR);
  830.  
  831.    FUNCTION
  832.        Diese Funktion schreibt einen kompletten ZConnect-Header in eine
  833.        Datei.
  834.  
  835.    INPUTS
  836.        list       - Zeiger auf die List-Struktur des zu schreibenden
  837.                     ZConnect-Headers
  838.        filehandle - Zeiger auf das FileHandler der Datei
  839.  
  840.    NOTES
  841.        Die Headerzeilen werden in folgendem Format in die Datei
  842.        geschrieben:
  843.  
  844.          <Kennung>:<TAB><Inhalt><CR><LF>
  845.  
  846.        Die Elemente zhl_ID und zhl_Contents werden unverändert in die Datei
  847.        geschrieben.
  848.  
  849.        Hinter dem Header wird keine Leerzeile (CR/LF) ausgegeben, die den
  850.        Header vom Body/Kommentar trennt.
  851.  
  852.        Die Ausgabe in die Datei geschieht mittels FWrite(), es ist also
  853.        darauf zu achten, nur gepufferte Ein-/Ausgabe zu benutzen.
  854.  
  855.    SEE ALSO
  856.        ZCon_HeaderToIBM(), ZCon_HeaderToISO(), dos.library/FWrite()
  857.